Rationale

BTrace has historically relied on libs=<profile> and $BTRACE_HOME/btrace-libs/<profile>/{boot,system}/*.jar to make application APIs (Spark, Hadoop, Kafka, …) visible to probes. That model has three structural problems:

• Classpath pollution. Profile JARs are appended to the bootstrap and system class loaders, which is highly privileged, conflicts with application shading, and cannot be isolated per probe.
• Fragile packaging. Resolution is heuristic (hardcoded agent-JAR name, URL string slicing, per-OS quirks). Renaming, JPMS, or non-filesystem deployments break it.
• Doesn't ship. Spark drivers/executors, Hadoop containers, and Kubernetes pods don't have a shared $BTRACE_HOME with a matching profile layout. Users end up with custom init containers, sidecars, or wrapper scripts just to deliver one extra JAR.

This PR introduces three complementary mechanisms to fix this: provided-style extensions (APIs on bootstrap, implementation reflective and isolated), @ExternalType adapter generation (build-time boilerplate elimination), and fat agents (a single JAR containing the agent plus embedded extensions, built via a Gradle or Maven plugin).

Usability Improvements

• Single-JAR deployment. java -javaagent:btrace-agent-fat.jar is now enough for Spark/Hadoop/K8s — no $BTRACE_HOME, no profile directory, no sidecars.
• No more classpath injection. Provided-style extensions keep only minimal API types on bootstrap; the impl lives in an isolated extension class loader and resolves app types via TCCL. Application shading and version conflicts stop being BTrace's problem.
• @ExternalType annotation processor. Annotate an interface with @ExternalType("fully.qualified.AppType") and the build generates a companion $Ext class with typed, lazily-resolved static dispatchers per method. No manual MethodHandleCache / ClassLoadingUtil boilerplate for the common case.
• Build-time tooling. New Gradle plugins (org.openjdk.btrace.extension, org.openjdk.btrace.fat-agent) and a btrace-maven-plugin handle API/impl split, manifest metadata, permission scanning, relocations, multi-project auto-discovery, and annotation processor registration.
• Single-source module layout. Extensions now use a single Gradle module with separate source sets (api, impl, main) rather than separate projects, which simplifies build setup.
• Declarative, manifest-driven libs. The legacy libs= heuristic is replaced by explicit manifest attributes (BTrace-Boot-Libs, BTrace-System-Libs, BTrace-Embedded-Extensions) with deduplication, validation, and diagnostics.
• Working examples. btrace-extensions/examples/btrace-spark and btrace-extensions/examples/btrace-hadoop demonstrate the pattern end-to-end, including @ExternalType-based adapters.

Quick Start

1. Build a fat agent with Gradle

plugins {
    id 'org.openjdk.btrace.fat-agent' version "${btraceVersion}"
}

btraceFatAgent {
    baseName = 'my-btrace-agent'
    embedExtensions {
        project(':my-spark-extension')              // multi-project
        maven('io.btrace:btrace-metrics:2.3.0')     // external
    }
}

./gradlew fatAgentJar
# -> build/libs/my-btrace-agent.jar

2. Attach it

java -javaagent:/path/to/my-btrace-agent.jar=debug=true,port=2020 -jar your-app.jar

Embedded extensions are discovered automatically from the JAR manifest — no $BTRACE_HOME required.

3. Write a provided-style extension with @ExternalType

Declare the external type contract in the API source set — the annotation processor (auto-registered by the Gradle plugin) generates SparkListenerJobStartType$Ext:

// src/api/java/com/example/spark/api/SparkListenerJobStartType.java
@ExternalType("org.apache.spark.scheduler.SparkListenerJobStart")
public interface SparkListenerJobStartType {
    int jobId();
    long time();
}

Use the generated class directly in the impl — no manual MethodHandle or ClassLoadingUtil code needed:

// src/impl/java/com/example/spark/impl/SparkApiImpl.java
public final class SparkApiImpl extends Extension implements SparkApi {
    @Override
    public void onJobStart(Object event) {
        int  jobId = SparkListenerJobStartType$Ext.jobId(event);
        long ts    = SparkListenerJobStartType$Ext.time(event);
        // emit metrics / logs...
    }
}

The generated dispatcher resolves the external class lazily on the first call (via the object's defining class loader), caches the MethodHandle, and retries on subsequent calls if the class wasn't loaded yet — no ExceptionInInitializerError at extension load time.

For cases @ExternalType doesn't cover (field access, constructors, non-public visibility), the manual ClassLoadingUtil / MethodHandleCache helpers still work alongside generated adapters.

4. (Optional) Static external methods

Annotate an interface method with @ExternalType.Static — the processor generates a findStatic + TCCL-based dispatcher:

@ExternalType("org.example.Foo")
public interface FooType {
    @ExternalType.Static
    String create();  // -> Foo.create() via findStatic
}

Maven equivalent

<plugin>
  <groupId>org.openjdk.btrace</groupId>
  <artifactId>btrace-maven-plugin</artifactId>
  <configuration>
    <extensions>
      <extension>io.btrace:btrace-metrics:${btrace.version}</extension>
    </extensions>
  </configuration>
</plugin>

See docs/architecture/provided-style-extensions.md and docs/architecture/migrating-from-libs-profiles.md for the full walk-through.

Drawbacks and Remaining Issues

• @ExternalType v1 scope limits. The annotation processor does not cover field access (read/write), constructors, instanceof/checkcast on external types, chained @ExternalType references, or non-public methods. Use ClassLoadingUtil / MethodHandleCache directly for these.
• No hot-reload for embedded extensions. Updating an extension in a fat agent requires rebuilding the JAR and restarting the target JVM.
• Larger artifact. A fat agent is strictly bigger than the minimal agent; users who ship BTrace through a managed $BTRACE_HOME don't benefit from embedding.
• More boilerplate than profiles for non-@ExternalType cases. When @ExternalType doesn't cover your case, the provided-style pattern still requires explicit API/impl split and reflective adapters. It's a deliberate trade-off (isolation + portability), but the migration cost from existing profile-based setups is real.
• Reflective cost at the hot path. Even with cached MethodHandles (generated or manual), an adapter call is more expensive than a direct invocation. Very high-frequency probes should be profiled.
• libs= / profiles= still accepted. They are deprecated and log a warning; planned removal is N+2 minor releases. Until then, both code paths coexist and users can mix them (not recommended).
• Escape hatch kept for now. -Dbtrace.system.appendJar=/abs/path/lib.jar (requires -Dbtrace.trusted=true) exists for cases where immediate migration is impossible. It's restricted to BTRACE_HOME by default and is explicitly discouraged — expect it to be removed together with libs=.
• Fat-agent plugin API surface. The Gradle/Maven plugins are new; DSL and task names may still shift before the first stable release cut.

Documentation

Breaking Changes

• libs= and profiles= are deprecated. Planned removal: N+2 minor releases. A runtime warning is emitted on use.

🤖 Generated with Claude Code

This change is